Skip to main content
Version: 24.03

part_uniqueidpush

Unique ID Push​

Unique ID Push notifications are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available.

The solution is based on notification assets in the EDC (which is the same approach that is used for quality alerts & investigations). The customer creates a notification asset in the EDC and the customer's suppliers send their notifications (with the Unique Id) to this notification asset. As this notification asset is a general EDC asset - as for all EDC assets - access policies, usage policies and contract definitions must be created.

✋ It is important to understand that the customer (receiver) creates EDC asset and policies, and thus, the supplier (sender) of the Unique ID push notification must check during the EDC negotiation process if the conditions the receiver offers are acceptable for the sender.

Prerequisites and Constraints​

In order to be able to push Unique ID(s) of part(s) to the correct partner, it is required that the data provider (manufacturer) pushing the Unique IDs is aware of the BPN of the actual receiver of the part (i.e., the customer) or has enough data in its context to use BPDM functions to determine the BPN Number of the receiver.

For actively pushing Unique IDs, an EDC is required and the data provider needs to be enabled to execute the complete process including EDC communication and HTTP Push (i.e., HTTP POST) of the payload.

Secondly, EDCs are being used for the exchange and it is currently required to offer a HTTP POST API to receive the Unique IDs push at the receiver's side. This API needs to be registered in the EDC Catalog as a data offer and requires specific properties to be set to standardized values, as this allows discover-ability. Details still tbd.

Unique ID Push Process Overview​

How the actual process is triggered is application specific. It is recommended to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication).

The Unique ID push is initiated by the supplier (acting as sender) towards their customer (acting as receiver). Since the Unique ID of the asset (i.e., serial unit / batch) is unknown in the logistics process, the message needs to include local identifiers to be matched towards the information from the delivery documents and furthermore the internal data of the recipient's traceability solution.

Upon receipt of the message, the customer needs to match the local identifiers with its internal traceability records and attach each Unique ID to the respective data set. How this is done is depending on the customer's internal systems:

  • If there is an object for incoming deliveries, this event could be updated. Alternatively, if only production events are tracked, the data could be integrated at this point into the data provisioning pipeline's data structure for consumed materials.
  • In the end this enables the customer to integrate the child parts into the SingleLevelBomAsBuilt aspect.

Unique ID Push Process

Schema of Unique ID Push Notifications​

The notifications send to inform a customer about the creating of a new digital twin for one of the parts they received have a standardized format.

All endpoints as well as the schema of the notification below are described in detail in the Unique ID Push API documentation.

Adding the customer part id to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part id for their parts. But, in case the manufacturer knows the customer and the corresponding customer part id of its part though, it is required to always add the customer part id to the notification.

Notification Receiver (Customer)​

Here is a short overview what the receiver has to do when they want to support Unique Id Push notifications. This is an optional feature.

  • The receiver in this scenario is the customer of a part.
  • The receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured.
  • The EDC in which the notification EDC asset was created must be registered at the Discovery Service (so that the sender can find the partner's EDC which should receive notifications)
  • When the Receiver receives a Unique Id Push notification, it must process this notification after it was received by the EDC (in a Backend Data Service)
  • How the Receiver processes the notification is up to them, but the following steps are recommended:
    • Verify the correctness of the data in the notification (i.e., the receiver is actually the customer of this part).
    • Store the notification data for later.
    • Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to a supplier's Digital Twin Registry.
EDC Asset​

For the EDC asset for receiving Unique ID Push notifications, the following conventions apply:

  • The asset ID must be "uniqueidpushnnotification-receipt".

  • The following properties must be set for this asset:

    {
      "@context": {
        "edc": "https://w3id.org/edc/v0.0.1/ns/",
        "cx-common": "https://w3id.org/catenax/ontology/common#",
        "cx-taxo": "https://w3id.org/catenax/taxonomy#",
        "dct": "https://purl.org/dc/terms/"
      },
      "@id": "{{ _.assetId }}",
      "properties": {
        "dct:type": { "@id": "cx-taxo:ReceiveUniqueIdPushNotification" },
        "cx-common:version": "1.0",
        "asset:prop:id": "uniqueidpushnnotification-receipt",
        "asset:prop:type": "notification.trace.uniqueidpush",
        "asset:prop:notificationtype": "uniqueidpush",
        "asset:prop:notificationmethod": "receive"
      },
      "privateProperties": {},
      "dataAddress": {}
    }

    Properties "asset:prop:*" must still be added to be backward compatible with previous releases. Properties "dct:type" and "cx-common:version" are used to classify the asset and are explained in the Digital Twin KIT in more detail.

EDC Policies​

Access Policies A data provider can decide on its own what access policies they want to define for their notification asset. Based on the purpose of the asset, all suppliers of the data provider should in general be allowed to send notifications to this asset. Therefore, either a public access policy or a BPN-based access policy (allowing all suppliers) should be used.

Usage Policies In general, a data provider is free to decide which usage policies to define for its assets. For notifications, though, the data provider is actually the receiver of notifications, i.e., the usage policy here has the purpose to define what the data provider does or is allowed to do with the notifications. It's something the sender of the notification has to rely on and accept when sending its notification.

Keep in mind that usage policies currently aren't technically enforced by the EDC or other components.

✋ Usage Policy for Unique ID Push The Unique ID push notification endpoints are protected with a purpose-based usage policy and "purpose.trace.v1.aspects" as purpose.

Backend Data Service to Process Unique ID Push Notifications​

The receiver must setup a backend data service that provides an HTTP Endpoint for notifications. All endpoints as well as the schema of the notification below are described in detail in the Unique ID Push API documentation.

Notification Sender (Manufacturer, Supplier)​

Here is a short overview what the sender has to do when they want to support Unique Id Push notifications. This is an optional feature.

  • The Sender in this scenario is the manufacturer or supplier of a part.
  • When a new digital twin for a part was created, the manufacturer is responsible to send a Unique Id Push notification for this twin to the customer of this part.
  • It is recommended to send this notification as soon as possible, i.e., directly after the digital twin was created.
Mapping BPN to EDC URL with Discovery Service API​

The sender must first find the EDC of the customer to which the notification should be sent to. For this, the BPN of the customer is required. With this, the Discovery Service can be used to query for all EDCs of the customer. After that, the data catalog of each of these EDCs must be queried for the notification EDC asset as described above. If this notification EDC asset is found in one of these EDCs, the notification can be sent.

There should only be one EDC which provides the notification EDC asset for Unique Id Push. If more than one EDC (for the same BPN/partner) are found, this is considered a misconfiguration of the corresponding partner.